ICAL

Section: User Commands (1)
Updated: October 27, 1993
Index Return to Main Contents

NAME

ical - X based calendar program

DESCRIPTION

Ical provides an X interface for maintaining a calendar. A calendar is basically just a set of items. An item is either an appointment, or a notice. An appointment starts at a particular time of the day, and finishes at a particular time of the day. A notice does not have any starting or ending time. Notices are useful for marking certain days as special. For example, a calendar may contain a notice for April 15th indicating that taxes are due. When the documentation below refers to an item, it applies both to notices and appointments. The main features of ical are:
    * Items can be created edited and deleted easily.
    * Items can be cut, copied and pasted.
    * Items can be made to repeat in various ways.
    * Ical will post reminders for upcoming appointments.
    * Ical can print and list item occurrences.
    * An ical calendar can include other calendars.
    * Ical calendars can be shared by different users.

GENERAL OPTIONS

You can specify various command line options to control ical. The following general options can be used even when you are not logged in on an X display.

-calendar file-name: The calendar is read from the specified file. See the section ``CALENDAR FILE'' for more information.
-list: Print a listing of today's items and exit immediately. See the section ``LISTING ITEMS'' for details on the actual items printed by this option.
-show +days: Print a listing for items in the range [ today ... today + days - 1 ] and exit immediately. See the section ``LISTING ITEMS'' for details on the actual items printed by this option.

X OPTIONS

The following options are valid only if you are logged in on an X display.

-iconic: Start up with the main window iconified.
-popup: Popup a window containing a listing of today's items and exit as soon as the window is dismissed. See the section ``LISTING ITEMS'' for details on the actual items printed by this option.
-mono: Do not use colors even if the display supports them.
-geometry geometry: Use geometry as the geometry for the main window.
-fg color: Use color as the foreground for all windows.
-bg color: Use color as the background for all windows.
-display display: Run ical on the specified X display.

CALENDAR FILE

A calendar is stored in a calendar file. The default calendar file is named ``.calendar'' and is kept in the user's home directory. If the ``CALENDAR'' environment variable is set, its value is used as the name of the calendar file. The ``CALENDAR'' environment variable and the default can both be overridden by specifying a file name on the command line --- ``ical -calendar file-name''. Ical periodically saves any modifications made to a calendar to the corresponding calendar file. Changes can be explicitly saved to the calendar file by selecting the Save entry from the File menu. You can discard any un-saved changes made to the calendar by selecting the Re-Read entry from the File menu. The Re-Read entry is also useful for incorporating changes made to a shared calendar by other users. The Exit entry in the File menu saves any changes and then kills the calendar program.

WINDOWS

The main calendar window displays the appointments and notices for a particular date. The top left portion of the window contains a date selector. You can click on the various arrows to change the month or the year. The day of the month can be selected by clicking on the appropriate day in the month display. The date selector contains various other buttons for convenient date selection. The bottom left portion of the window contains the notices for the selected date. You can scroll this region by using the scroll bar. The right portion of the window contains the appointments for the selected day. You can scroll this region by using the scroll bar, or by dragging with the middle mouse button in the background. A menubar runs along the top of the calendar window. The File menu allows you to create and destroy application windows.

New Window: Opens a new calendar window. This new window can be used to view the items for a different date than the original window.
Close Window: Closes the selected window.

The bottom portion of the window contains a status line. This status line indicates the calendar from which the selected item comes and whether or not the selected item repeats.

NOTICES

You can enter notices by clicking in the background in the bottom-left portion of the main calendar window. This click will create a new notice for the selected date. You can enter text into the notice by typing into it while it is selected (selected notices are highlighted by being displayed in different colors). A notice can be selected for editing by clicking with left button.

APPOINTMENTS

You can enter appointments by left-clicking in the background in the right portion of the main calendar window. This click will create a new appointment for the selected date. The start time for this appointment is determined by the click location. You can move the appointment by dragging it with the middle mouse button held down. The appointment can be resized by dragging with the right mouse button held down. Appointment text can be edited by typing into the appointment window while it is selected. If the appointment text you are typing in does not fit into the appointment area, then it will overflow out of the appointment area, but will be editable normally. If you do not like overflowing text, you should turn off the Allow Text Overflow option in the Options menu. With this option turned off, if the current text completely fills the area allocated to the appointment, then any attempts to add to the appointment text will be ignored until the appointment is enlarged with the right mouse button. Likewise, the right mouse button will refuse to shrink an appointment window if the appointment text completely fills the appointment window.

ALARMS

Ical generates alarms for appointments. By default, the first alarm is generated fifteen minutes before the appointment is supposed to start and successive alarms are generated every five minutes until the appointment actually starts. You can change this default behavior by selecting the Default Alarms entry from the Option menu. You can also change the timings of these alarms on an appointment-by-appointment basis by selecting an appointment and then selecting the Change Alarms entry in the Edit menu.

REPEATING ITEMS

Items can be made to repeat in various ways. Item repetition can be controlled by using the entries in the Repeat menu. These entries make the item repeat in certain frequently used ways. For example, the Monthly entry makes the selected item repeat once per month. In addition to making an item repeat in one of the pre-defined ways, you can also restrict an item's starting and finishing date by selecting the Make First Date or the Make Last Date entry from the Repeat menu. Normally, a modication to a repeating item applies to all occurrences of that item. A single occurrence of a repeating item can be modified by selecting the occurrence and then choosing the Make Unique entry from the Edit menu. The selected occurrence can now be modified independently of the repeating item.

X SELECTION

Dragging with the left mouse button in a selected appointment or notice sets the X selection. You can use the Insert Selection entry in the Edit menu to insert the current X selection into a selected item. You can use the Import Selection entry in the edit menu to insert the current X selection as a new item. Ical guesses the date and time for the new item from the contents of the selection.

CLIPBOARD

The application has a clipboard that can store a single item. The Copy entry in the Edit menu copies the selected item into the clipboard. The Cut entry does the same, but it also deletes the item from the calendar. If the selected item repeats, then the Cut command allows the user to delete all occurrences of the item, or just the selected occurrence. However, if the selected item does not belong to you, then Cut just hides the item from you. Other people will still see the item. An item in the clipboard can be inserted into the current day by selecting Paste from the Edit menu. The newly pasted item loses all repetition information, and occurs just on the day in which it was pasted.

HIGHLIGHTING ITEMS

By default, if any item occurs on a date, then the date is highlighted in the date selector located in the top-left corner of the calendar window. You can use the Highhlight sub-menu in the Edit menu to control this highlighting behavior on an item-by-item basis.

Always: The item always causes the corresponding date to be highlighted. This is the default behavior.
Until Occurrence: The item causes the corresponding date to be highlighted if and only if the date is not in the past.
Never: The item never causes the corresponding date to be highlighted.
As Holiday: The item causes the corresponding date to be highlighted as a holiday.

LISTING ITEMS

You can generate listings of imminent items by selecting one of the listing options in the List menu. You can also use the command line options -list, -show, or -popup to generate item listings. The command line options are most useful in ``.login'' files. By default an item is included in a listing for a particular date if it occurs either on that date, or on the very next day. Sometimes, you want to include an item in listings for earlier dates. For example, if you have an item reminding you of a birthday on March 17th, you might want this item to be included in all listings from March 7th to March 17th so that you will have enough time to go out and buy a present. You can achieve this effect by selecting the Ten Days Early option from the List Item entry in the Edit menu. Note that this will only change the listing behavior for the selected item. You can make this change for all items you create from now on by using the Default Listings entry in the Options menu. The A Day Early entry restores the default behavior. The On Occurence entry marks the item so that it is only included in the listing for a particular date if it occurs on that date.

PRINTING

Calendar contents can be printed by selecting the Print option from the File menu. The user has the option of saving the print-out to a file, previewing the print-out by specifying a PostScript displaying program, or sending the print-out directly to a PostScript printer.

INCLUDING CALENDARS

You can include other calendars into your private calendar. This facility is mainly useful for allowing a group of people to share a common set of items. For example, members of a particular group might have a calendar that contains the birthdays for each member of the group. This calendar can be included in each group member's private calendar. You can include a calendar by selecting the Include Calendar entry from the File menu. You can remove an included calendar by selecting the Remove Calendar entry from the File menu. An item can be moved between calendars by selecting the Move Item To ... entry from the Edit menu. You can list all items in a particular calendar by selecting the From Calendar ... entry from the List menu.

CUSTOMIZATION

Limited portions of ical can be customized via the Options menu.

Appointment Range: Subset of a day displayed by default in the appointment listing. The factory settings display 8:00am to 6:00pm.
Notice Window Height: This entry can be used to change the height of the notice window.
Item Width: This entry can be used to change the width of displayed appointments and notices.
Allow Text Overflow: If this option is selected, then you can type in any amount of text into an appointment. The part of the text that does not fit into the appointment will be allowed to overflow out of the appointment. If you do not like text overflowing out of an appointment, then you should turn off this option.
Display Am/Pm: If this option is selected, time will be printed in twelve hour mode with ``am'' or ``pm'' indicators. Otherwise, time will be printed in twenty-four hour mode.
Start Week on Monday: If this option is selected, month displays will start each week off on a Monday. Otherwise, each week will start on a Sunday.
Default Alarms: Use this menu entry to change the time intervals at which alarms go off. The factory settings cause alarms to be triggered fifteen minutes before each appointment, and then once every five minutes until the appointment actually starts. This menu entry changes the default alarm behavior for all appointments. You can override this default behavior on an appointment-by-appointment basis by selecting an appointment and then selecting the Change Alarms entry in the Edit menu.
Default Listings: This menu can be used to select the default listing behavior for newly created items. If the On Occurrence entry is selected, then a newly created item will only be shown in the listing of the day on which the item occurs. If the A Day Early entry is selected, then a new item will be shown in listings starting a day before the item occurrence. Similarly, the other menu entries can be selected to make new items show up in listings a number of days before their actual occurrence. This menu selects the default behavior for new items. Individual item behavior can be controlled by similar entries in the Edit menu.

You can specify several X resources to customize the rest of the appearance and behavior of ical.

BEHAVIOR

Ical.pollSeconds: Calendar files are saved, and changes made by other people are incorporated once every pollSeconds seconds. The default value is 30. If ical appears sluggish, or if it is using too much CPU time, increase this value.

DIMENSIONS

Ical.itemSelectWidth: The border width of selected items is set to the value of this option to display the selected status of the item to to the user. On color displays, the default value of this option is ``1'' because on color displays selection is indicated by changing the color of the selected item. On monochrome displays, the default value of itemSelectWidth is ``4''.
Ical.Dayview.geometry: X geometry specification for main calendar window. Usually, you will just specify the window position here. The size of the window is easier to control via the Options menu.
Ical.Reminder.geometry: X geometry specification for alarms. Usually, you will just specify the window position here. The window size will be calculated automatically.
Ical.Listing.geometry: X geometry specification for item listings. Usually, you will just specify the window position here. The window size will be calculated automatically.

COLORS

If ical windows show up with illegible colors (not enough distinction between background and foreground), it may be because your X resources contain definitions for ``*foreground'' or ``*background'' that conflict with ical colors. In general, it is a bad idea to define ``*foreground'' and ``*background'' in your resources because it will break a number of programs. You will be better off defining resources on an application by application basis.

Ical*foreground
Ical*background: Set the colors used for most of the ical windows.
Ical.itemFg
Ical.itemBg: The foreground and background colors for unselected items. The default foreground is black and the default background is gray.
Ical.itemSelectFg
Ical.itemSelectBg: The foreground and background colors for selected items. The default foreground is yellow and the default background is blue.
Ical.apptLineColor: The color for the background lines and times displayed in the appointment window.
Ical.weekdayColor: The color used to display days of the week. The default is black.
Ical.weekendColor: The color used to display weekends. The default is red.
Ical.interestColor: The color used to highlight interesting dates. The default is blue.

FONTS

Ical.fontFamily: Preferred font family. Fonts for various purposes are obtained from this family unless overridden with one of the specifications below. The default font family is ``times''. Some other font families you can specify here are ``charter'', ``new century schoolbook'', and ``helvetica''.
Ical.itemFont: Font used to display item contents.
Ical.weekdayFont: Font used for displaying days of the week.
Ical.weekendFont: Font used for displaying weekends.
Ical.interestFont: Font used to highlight interesting dates.
Ical.smallHeadingFont: Font used for small headings.
Ical.largeHeadingFont: Font used for large headings. ds cL <class>
Ical**font:: Font used for windows of a certain class. Possible values for are ``Dialog'', ``Button'', ``Label'', ``Menubutton'', ``Menu'', ``Listbox'', and ``Reminder''.